home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / k3bjob.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-05-27  |  9.3 KB  |  312 lines
  1. /*
  2.  *
  3.  * $Id: k3bjob.h 619556 2007-01-03 17:38:12Z trueg $
  4.  * Copyright (C) 2003 Sebastian Trueg <trueg@k3b.org>
  5.  *
  6.  * This file is part of the K3b project.
  7.  * Copyright (C) 1998-2007 Sebastian Trueg <trueg@k3b.org>
  8.  *
  9.  * This program is free software; you can redistribute it and/or modify
  10.  * it under the terms of the GNU General Public License as published by
  11.  * the Free Software Foundation; either version 2 of the License, or
  12.  * (at your option) any later version.
  13.  * See the file "COPYING" for the exact licensing terms.
  14.  */
  15.  
  16.  
  17. #ifndef K3BJOB_H
  18. #define K3BJOB_H
  19.  
  20. #include <qobject.h>
  21. #include <qptrlist.h>
  22. #include "k3bjobhandler.h"
  23. #include "k3b_export.h"
  24.  
  25. class K3bDoc;
  26. namespace K3bDevice {
  27.   class Device;
  28. }
  29.  
  30.  
  31. /**
  32.  * This is the baseclass for all the jobs in K3b which actually do the work like burning a cd!
  33.  * The K3bJob object takes care of registering with the k3bcore or with a parent K3bJob.
  34.  *
  35.  * Every job has a jobhandler which can be another job (in which case the job is handled as
  36.  * a subjob) or an arbitrary class implementing the K3bJobHandler interface.
  37.  *
  38.  * A Job should never create any widgets. User interaction should be done through the methods
  39.  * questionYesNo, waitForMedia.
  40.  *
  41.  * @author Sebastian Trueg
  42.  */
  43. class LIBK3B_EXPORT K3bJob : public QObject, public K3bJobHandler
  44. {
  45.   Q_OBJECT
  46.  
  47.  public:
  48.   virtual ~K3bJob();
  49.  
  50.   /**
  51.    * \reimplemented from K3bJobHandler
  52.    */
  53.   bool isJob() const { return true; }
  54.  
  55.   K3bJobHandler* jobHandler() const { return m_jobHandler; }
  56.  
  57.   /**
  58.    * Is the job active?
  59.    * The default implementation is based on the jobStarted() and jobFinished()
  60.    * methods and there is normally no need to reimplement this.
  61.    */
  62.   virtual bool active() const { return m_active; }
  63.  
  64.   /**
  65.    * The default implementation is based on the canceled() signal.
  66.    *
  67.    * This means that one cannot count on this value being valid
  68.    * in a slot connected to the canceled() signal. It is, however, save
  69.    * to call this method from a slot connected to the finished() signal
  70.    * in case the job makes proper usage of the jobStarted/jobFinished
  71.    * methods.
  72.    */
  73.   virtual bool hasBeenCanceled() const { return m_canceled; }
  74.  
  75.   virtual QString jobDescription() const { return "K3bJob"; }
  76.   virtual QString jobDetails() const { return QString::null; }
  77.  
  78.   /**
  79.    * @returns the number of running subjobs.
  80.    * this is useful for proper cancellation of jobs.
  81.    */
  82.   unsigned int numRunningSubJobs() const;
  83.  
  84.   const QPtrList<K3bJob>& runningSubJobs() const { return m_runningSubJobs; }
  85.  
  86.   /**
  87.    * \deprecated
  88.    */
  89.   virtual void connectSubJob( K3bJob* subJob,
  90.                   const char* finishedSlot = 0,
  91.                   bool progress = false,
  92.                   const char* progressSlot = 0,
  93.                   const char* subProgressSot = 0,
  94.                   const char* processedSizeSlot = 0,
  95.                   const char* processedSubSizeSlot = 0 );
  96.  
  97.   static const char* DEFAULT_SIGNAL_CONNECTION;
  98.  
  99.   /**
  100.    * \param newTaskSlot    If DEFAULT_SIGNAL_CONNECTION the newTask signal from the subjob will 
  101.    *                       be connected to the newSubTask signal
  102.    * \param newSubTaskSlot If DEFAULT_SIGNAL_CONNECTION the newSubTask signal from the subjob 
  103.    *                       will create an infoMessage signal
  104.    * \param progressSlot   If DEFAULT_SIGNAL_CONNECTION the percent signal of the subjob will be 
  105.    *                       connected to the subPercent signal.
  106.    * debuggingOutput and infoMessage will always be direcctly connected.
  107.    *
  108.    * If a parameter is set to 0 it will not be connected at all
  109.    */
  110.   virtual void connectSubJob( K3bJob* subJob,
  111.                   const char* finishedSlot = DEFAULT_SIGNAL_CONNECTION,
  112.                   const char* newTaskSlot = DEFAULT_SIGNAL_CONNECTION,
  113.                   const char* newSubTaskSlot = DEFAULT_SIGNAL_CONNECTION,
  114.                   const char* progressSlot = DEFAULT_SIGNAL_CONNECTION,
  115.                   const char* subProgressSlot = DEFAULT_SIGNAL_CONNECTION,
  116.                   const char* processedSizeSlot = DEFAULT_SIGNAL_CONNECTION,
  117.                   const char* processedSubSizeSlot = DEFAULT_SIGNAL_CONNECTION );
  118.  
  119.   /**
  120.    * Message types to be used in combination with the infoMessage signal.
  121.    *
  122.    * \see infoMessage()
  123.    */
  124.   enum MessageType { 
  125.     INFO,     /**< Informational message. For example a message that informs the user about what is
  126.          currently going on */
  127.     WARNING,  /**< A warning message. Something did not go perfectly but the job may continue. */
  128.     ERROR,    /**< An error. Only use this message type if the job will actually fail afterwards
  129.          with a call to jobFinished( false ) */
  130.     SUCCESS   /**< This message type may be used to inform the user that a sub job has 
  131.          been successfully finished. */
  132.   };
  133.  
  134.   /**
  135.    * reimplemented from K3bJobHandler
  136.    */
  137.   int waitForMedia( K3bDevice::Device*,
  138.             int mediaState = K3bDevice::STATE_EMPTY,
  139.             int mediaType = K3bDevice::MEDIA_WRITABLE_CD,
  140.             const QString& message = QString::null );
  141.   
  142.   /**
  143.    * reimplemented from K3bJobHandler
  144.    */
  145.   bool questionYesNo( const QString& text,
  146.               const QString& caption = QString::null,
  147.               const QString& yesText = QString::null,
  148.               const QString& noText = QString::null );
  149.  
  150.   /**
  151.    * reimplemented from K3bJobHandler
  152.    */
  153.   void blockingInformation( const QString& text,
  154.                 const QString& caption = QString::null );
  155.  
  156.  public slots:
  157.   /**
  158.    * This is the slot that starts the job. The first call should always
  159.    * be jobStarted().
  160.    *
  161.    * Once the job has finished it has to call jobFinished() with the result as
  162.    * a parameter.
  163.    *
  164.    * \see jobStarted()
  165.    * \see jobFinished()
  166.    */
  167.   virtual void start() = 0;
  168.  
  169.   /**
  170.    * This slot should cancel the job. The job has to emit the canceled() signal and make a call
  171.    * to jobFinished().
  172.    * It is not important to do any of those two directly in this slot though.
  173.    */
  174.   virtual void cancel() = 0;
  175.  
  176.   void setJobHandler( K3bJobHandler* );
  177.  
  178.  signals:
  179.   void infoMessage( const QString& msg, int type );
  180.   void percent( int p );
  181.   void subPercent( int p );
  182.   void processedSize( int processed, int size );
  183.   void processedSubSize( int processed, int size );
  184.   void newTask( const QString& job );
  185.   void newSubTask( const QString& job );
  186.   void debuggingOutput(const QString&, const QString&);
  187.   void data( const char* data, int len );
  188.   void nextTrack( int track, int numTracks );
  189.  
  190.   void canceled();
  191.  
  192.   /**
  193.    * Emitted once the job has been started. Never emit this signal directly.
  194.    * Use jobStarted() instead, otherwise the job will not be properly registered
  195.    */
  196.   void started();
  197.  
  198.   /**
  199.    * Emitted once the job has been finshed. Never emit this signal directly.
  200.    * Use jobFinished() instead, otherwise the job will not be properly deregistered
  201.    */
  202.   void finished( bool success );
  203.  
  204.  protected:
  205.   /**
  206.    * \param hdl the handler of the job. This allows for some user interaction without
  207.    *            specifying any details (like the GUI).
  208.    *            The job handler can also be another job. In that case this job is a sub job
  209.    *            and will be part of the parents running sub jobs.
  210.    *
  211.    * \see runningSubJobs()
  212.    * \see numRunningSubJobs()
  213.    */
  214.   K3bJob( K3bJobHandler* hdl, QObject* parent = 0, const char* name = 0 );
  215.  
  216.   /**
  217.    * Call this in start() to properly register the job and emit the started() signal.
  218.    * Do never emit the started() signal manually.
  219.    *
  220.    * Always call K3bJob::jobStarted in reimplementations.
  221.    */
  222.   virtual void jobStarted();
  223.  
  224.   /**
  225.    * Call this at the end of the job to properly deregister the job and emit the finished() signal.
  226.    * Do never emit the started() signal manually.
  227.    *
  228.    * Always call K3bJob::jobFinished in reimplementations.
  229.    */
  230.   virtual void jobFinished( bool success );
  231.  
  232.  private slots:
  233.   void slotCanceled();
  234.   void slotNewSubTask( const QString& str );
  235.  
  236.  private:
  237.   void registerSubJob( K3bJob* );
  238.   void unregisterSubJob( K3bJob* );
  239.  
  240.   K3bJobHandler* m_jobHandler;
  241.   QPtrList<K3bJob> m_runningSubJobs;
  242.  
  243.   bool m_canceled;
  244.   bool m_active;
  245.  
  246.   class Private;
  247.   Private* d;
  248. };
  249.  
  250.  
  251. /**
  252.  * Every job used to actually burn a medium is derived from K3bBurnJob.
  253.  * This class implements additional signals like buffer status or writing speed
  254.  * as well as a handling of the used writing application.
  255.  */
  256. class LIBK3B_EXPORT K3bBurnJob : public K3bJob
  257. {
  258.   Q_OBJECT
  259.     
  260.  public:
  261.   K3bBurnJob( K3bJobHandler* hdl, QObject* parent = 0, const char* name = 0 );
  262.   virtual ~K3bBurnJob();
  263.  
  264.   /**
  265.    * The writing device used by this job.
  266.    */    
  267.   virtual K3bDevice::Device* writer() const { return 0; }
  268.  
  269.   /**
  270.    * use K3b::WritingApp
  271.    */
  272.   int writingApp() const { return m_writeMethod; }
  273.  
  274.   /**
  275.    * K3b::WritingApp "ored" together
  276.    */
  277.   virtual int supportedWritingApps() const;
  278.  
  279.  public slots:
  280.   /**
  281.    * use K3b::WritingApp
  282.    */
  283.   void setWritingApp( int w ) { m_writeMethod = w; }
  284.  
  285.  signals:
  286.   void bufferStatus( int );
  287.  
  288.   void deviceBuffer( int );
  289.  
  290.   /**
  291.    * @param speed current writing speed in Kb
  292.    * @param multiplicator use 150 for CDs and 1380 for DVDs
  293.    * FIXME: maybe one should be able to ask the burnjob if it burns a CD or a DVD and remove the 
  294.    *        multiplicator parameter)
  295.    */
  296.   void writeSpeed( int speed, int multiplicator );
  297.  
  298.   /**
  299.    * This signal may be used to inform when the burning starts or ends
  300.    * The BurningProgressDialog for example uses it to enable and disable
  301.    * the buffer and writing speed displays.
  302.    */
  303.   void burning(bool);
  304.  
  305.  private:
  306.   int m_writeMethod;
  307.  
  308.   class Private;
  309.   Private* d;
  310. };
  311. #endif
  312.